Skip to main content
Feedback

Example: configuring outbound mTLS for a backend that requires a client certificate

Some backends, for example banking, government, or other regulatory-mandated systems, refuse a connection unless the caller presents a valid client certificate during the TLS handshake. When your API's backend enforces this, you configure Boomi API Gateway's outbound mTLS so the Gateway authenticates itself before your API's request ever reaches the backend's application logic. Refer to Outbound SSL settings for the concepts and full field reference behind the steps in this example.

You'll use the following in the Boomi Platform to configure and verify outbound mTLS end to end:

  • Integration: to manage the client certificate as an Integration Certificate component.
  • API Management and API Gateway: to configure Outbound SSL settings and deploy the API the Gateway protects.
  • A backend that enforces mutual TLS: this example uses a free, public mTLS test endpoint so you can complete every step and see a real pass/fail result without needing a production backend.

Prerequisites

  • An API deployed to a Gateway in API Management. Refer to Creating an API component if you don't have one yet.
  • Access to the Outbound SSL settings for that Gateway.
  • A tool for sending HTTPS requests with a client certificate attached, such as Postman or curl.

Scenario overview

In this example, you configure the strictest combination of outbound mTLS settings, since it exercises every field described in Configuration reference:

  • Outbound SSL Settings: Enabled
  • Outbound mTLS: Enabled, so the Gateway presents a client certificate to the backend
  • Trust All: Disabled, so the Gateway validates the backend's certificate against a trusted certificate you configure
  • Hostname Verifier: Enabled, so the Gateway also confirms the backend certificate's hostname matches the server it connects to

Step 1: Get a client certificate for the Gateway to present

If your backend's administrator already issued you a client certificate and private key for this integration, skip to Step 2. Otherwise, generate a free test certificate:

  1. Go to a certificate authority (CA) testing tool that issues CA-signed certificates for mutual TLS testing, such as getaCert.com's CA-Signed Certificate tool.
  2. Enter a Common Name (CN) for the certificate. Since this is a test certificate, it does not need to match a domain you own.
  3. Complete the remaining steps (Identity, Options) with default or placeholder values, then select Review and generate the certificate.
  4. Download the PKCS#12 (.p12) bundle. Note the passphrase shown on the results page; you need it in the next step.

Step 2: Add the certificate as an Integration Certificate component

  1. In Integration, create a new Certificate component and upload the .p12 file from Step 1, along with its passphrase.
  2. Save the component. You select this component as the Gateway's Keystore Certificate in the next step.

Step 3: Configure Outbound SSL settings on the Gateway

  1. In Gateway Settings, open the Outbound SSL page.
  2. Enable Outbound SSL Settings.
  3. Enable Outbound MTLS, since the backend in this scenario requires a client certificate.
  4. Disable Trust All, so the Gateway validates the backend's certificate instead of accepting it unconditionally.
  5. Enable Hostname Verifier, so the Gateway also checks that the backend certificate's hostname matches the server it connects to.
  6. Set Keystore Certificate to the Integration Certificate component you created in Step 2.
  7. Add the backend's own server certificate (or its issuing CA) to Gateway Trusted Certificates, since Trust All is off. For the getaCert.com test endpoint used in this example, this is the getaCert CA certificate, available from getaCert.com's CA Root Certificates page.
  8. Select Save.

Refer to Configure outbound SSL settings in a Gateway for the full field-by-field procedure this step summarizes.

Step 4: Point your API's backend at the mTLS test endpoint

  1. In Integration, open the process (or connector) that this API deploys.
  2. Set the backend/target URL to the mTLS test endpoint, for example https://getacert.com:8443/.
  3. Save the process and redeploy the API so the updated target takes effect.

Step 5: Call the API and verify the handshake

  1. Send a GET request to your API's Gateway URL, the same way any consumer would call it. You do not need to attach a client certificate yourself; the Gateway presents the one you configured in Step 3.

  2. A successful outbound mTLS handshake returns the backend's response through your API, for example:

    {
      "status": "ok",
      "message": "mTLS handshake successful! Your certificate is valid and signed by the getaCert CA.",
      "client_dn": "CN=<the Common Name you set in Step 1>",
      "valid_from": "<start date>",
      "valid_until": "<expiration date>"
    }

  3. If the call fails instead, check the response against Errors:

    • A 403 typically means the Keystore Certificate isn't set or Outbound mTLS isn't actually enabled on the Gateway or the API.
    • A 502 typically means Trust All is off and the backend's certificate isn't in Gateway Trusted Certificates, or Hostname Verifier is on and the backend's certificate hostname doesn't match the server you targeted.
On this Page